/*
 *  @(#)Repository.java    0.3 16/04/2009
 */
package org.miao.example.repository;

import java.util.List;
import java.util.Map;

/**
 * 通用Repository接口对象
 * 规定了基本的持久化操作
 * @author Miao
 * @version 0.3
 * @since 0.3
 */
public interface Repository<T> {

    /**
     * 持久化指定对象
     * @param entity 持久化对象
     * @since 0.3
     */
    public void persist(T entity);

    /**
     * 持久化上下文受管
     * @param <T> 返回的受管对象类型
     * @param entity 要被上下文管理的对象
     * @return 受管对象
     * @since 0.3
     */
    public <T> T merge(T entity);

    /**
     * 移除受管对象
     * @param entity 移除的对象
     * @since 0.3
     */
    public void remove(T entity);

    /**
     * 移除受管对象
     * @param entityClass 指定类
     * @param id id主键
     * @since 0.3
     */
    public void remove(Class entityClass, Object id);

    /**
     * 判断该对象是否存在
     * @param entity 判断的对象
     * @return 是否存在
     * @since 0.3
     */
    public boolean contains(T entity);

    /**
     * 刷新受管对象状态
     * 从数据库更新受管对象
     * @param entity 刷新的对象
     * @since 0.3
     */
    public void refresh(T entity);

    /**
     * 刷新受管对象，更新数据库
     * @since 0.3
     */
    public void flush();

    /**
     * 清理上下文中的受管对象
     * @since 0.3
     */
    public void clear();

    /**
     * 查询指定类的指定对象
     * @param entityClass 指定类
     * @param id 主键
     * @return 对象
     * @since 0.3
     */
    public T find(Class entityClass, Object id);

    /**
     * 命名查询
     * @param name 命名名称
     * @return 对象列表
     * @since 0.3
     */
    public List<T> findByByNamedQuery(String name);

    /**
     * 带参数的命名查询
     * @param name 命名名称
     * @param parameters 参数
     * @return 对象列表
     * @since 0.3
     */
    public List<T> findByByNamedQuery(String name, Object... parameters);

    /**
     * 通过预定义语句查询
     * @param name 预定义语句名
     * @param parameters 参数
     * @param orders 排序
     * @return 对象列表
     * @since 0.3
     */
    public List<T> findByNamed(String name, Map<String, Object> parameters, List<String> orders);

    /**
     * 通过预定义语句统计
     * @param name 预定义语句名
     * @param type 统计类型
     * @param parameters 参数
     * @return 统计结果
     * @since 0.3
     */
    public Object statistics(String name, statisticType type, Map<String, Object> parameters);

    /**
     * 通过预定义语句进行分页查询
     * @param name 预定义语句名
     * @param parameters 参数
     * @param currentPage 当前页
     * @param pageSize 单页记录数量
     * @return 分页组件
     * @since 0.3
     */
    public PageBean<T> findPageByNamed(String name, Map<String, Object> parameters, List<String> orders, int currentPage, int pageSize);

    /**
     * 对对象使用读锁
     * @param entity 对象
     * @since 0.3
     */
    public void lockByRead(T entity);

    /**
     * 对对象使用写锁
     * @param entity 对象
     * @since 0.3
     */
    public void lockByWrite(T entity);
}
